<!DOCTYPE html>

<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/">
<title>Genshi: Upgrading Genshi</title>
<link rel="stylesheet" href="common/style/edgewall.css" type="text/css">
</head>
<body>
<div class="document" id="upgrading-genshi">
    <div id="navigation">
      <span class="projinfo">Genshi 0.5.1</span>
      <a href="index.html">Documentation Index</a>
    </div>
<h1 class="title">Upgrading Genshi</h1>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#upgrading-from-genshi-0-4-x-to-0-5-x" id="id1" name="id1">1   Upgrading from Genshi 0.4.x to 0.5.x</a><ul class="auto-toc">
<li><a class="reference" href="#error-handling" id="id2" name="id2">1.1   Error Handling</a></li>
<li><a class="reference" href="#match-template-processing" id="id3" name="id3">1.2   Match Template Processing</a></li>
<li><a class="reference" href="#text-templates" id="id4" name="id4">1.3   Text Templates</a></li>
<li><a class="reference" href="#markup-constructor" id="id5" name="id5">1.4   <tt class="docutils literal"><span class="pre">Markup</span></tt> Constructor</a></li>
<li><a class="reference" href="#template-constructor" id="id6" name="id6">1.5   <tt class="docutils literal"><span class="pre">Template</span></tt> Constructor</a></li>
</ul>
</li>
<li><a class="reference" href="#upgrading-from-genshi-0-3-x-to-0-4-x" id="id7" name="id7">2   Upgrading from Genshi 0.3.x to 0.4.x</a></li>
<li><a class="reference" href="#upgrading-from-markup" id="id8" name="id8">3   Upgrading from Markup</a></li>
</ul>
</div>
<div class="section">
<h1><a id="upgrading-from-genshi-0-4-x-to-0-5-x" name="upgrading-from-genshi-0-4-x-to-0-5-x">1   Upgrading from Genshi 0.4.x to 0.5.x</a></h1>
<div class="section">
<h2><a id="error-handling" name="error-handling">1.1   Error Handling</a></h2>
<p>The default error handling mode has been changed to "strict". This
means that accessing variables not defined in the template data will
now generate an immediate exception, as will accessing object
attributes or dictionary keys that don't exist. If your templates rely
on the old lenient behavior, you can configure Genshi to use that
instead. See the documentation for details on how to do that. But be
warned that lenient error handling may be removed completely in a
future release.</p>
</div>
<div class="section">
<h2><a id="match-template-processing" name="match-template-processing">1.2   Match Template Processing</a></h2>
<p>There has also been a subtle change to how <tt class="docutils literal"><span class="pre">py:match</span></tt> templates are
processed: in previous versions, all match templates would be applied
to the content generated by the matching template, and only the
matching template itself was applied recursively to the original
content. This behavior resulted in problems with many kinds of
recursive matching, and hence was changed for 0.5: now, all match
templates declared before the matching template are applied to the
original content, and match templates declared after the matching
template are applied to the generated content. This change should not
have any effect on most applications, but you may want to check your
use of match templates to make sure.</p>
</div>
<div class="section">
<h2><a id="text-templates" name="text-templates">1.3   Text Templates</a></h2>
<p>Genshi 0.5 introduces a new, alternative syntax for text templates,
which is more flexible and powerful compared to the old syntax. For
backwards compatibility, this new syntax is not used by default,
though it will be in a future version. It is recommended that you
migrate to using this new syntax. To do so, simply rename any
references in your code to <tt class="docutils literal"><span class="pre">TextTemplate</span></tt> to <tt class="docutils literal"><span class="pre">NewTextTemplate</span></tt>. To
explicitly use the old syntax, use <tt class="docutils literal"><span class="pre">OldTextTemplate</span></tt> instead, so
that you can be sure you'll be using the same language when the
default in Genshi is changed (at least until the old implementation is
completely removed).</p>
</div>
<div class="section">
<h2><a id="markup-constructor" name="markup-constructor">1.4   <tt class="docutils literal"><span class="pre">Markup</span></tt> Constructor</a></h2>
<p>The <tt class="docutils literal"><span class="pre">Markup</span></tt> class no longer has a specialized constructor. The old
(undocumented) constructor provided a shorthand for doing positional
substitutions. If you have code like this:</p>
<div class="highlight"><pre><span class="n">Markup</span><span class="p">(</span><span class="s">'&lt;b&gt;</span><span class="si">%s</span><span class="s">&lt;/b&gt;'</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
</pre></div>
<p>You must replace it by the more explicit:</p>
<div class="highlight"><pre><span class="n">Markup</span><span class="p">(</span><span class="s">'&lt;b&gt;</span><span class="si">%s</span><span class="s">&lt;/b&gt;'</span><span class="p">)</span> <span class="o">%</span> <span class="n">name</span>
</pre></div>
</div>
<div class="section">
<h2><a id="template-constructor" name="template-constructor">1.5   <tt class="docutils literal"><span class="pre">Template</span></tt> Constructor</a></h2>
<p>The constructor of the <tt class="docutils literal"><span class="pre">Template</span></tt> class and its subclasses has changed
slightly: instead of the optional <tt class="docutils literal"><span class="pre">basedir</span></tt> parameter, it now expects
an (also optional) <tt class="docutils literal"><span class="pre">filepath</span></tt> parameter, which specifies the absolute
path to the template. You probably aren't using those constructors
directly, anyway, but using the <tt class="docutils literal"><span class="pre">TemplateLoader</span></tt> API instead.</p>
</div>
</div>
<div class="section">
<h1><a id="upgrading-from-genshi-0-3-x-to-0-4-x" name="upgrading-from-genshi-0-3-x-to-0-4-x">2   Upgrading from Genshi 0.3.x to 0.4.x</a></h1>
<p>The modules <tt class="docutils literal"><span class="pre">genshi.filters</span></tt> and <tt class="docutils literal"><span class="pre">genshi.template</span></tt> have been
refactored into packages containing multiple modules. While code using
the regular APIs should continue to work without problems, you should
make sure to remove any leftover traces of the files <tt class="docutils literal"><span class="pre">filters.py</span></tt>
and <tt class="docutils literal"><span class="pre">template.py</span></tt> in the <tt class="docutils literal"><span class="pre">genshi</span></tt> package on the installation
path (including the corresponding <tt class="docutils literal"><span class="pre">.pyc</span></tt> files). This is not
necessary when Genshi was installed as a Python egg.</p>
<p>Results of evaluating template expressions are no longer implicitly
called if they are callable. If you have been using that feature, you
will need to add the parenthesis to actually call the function.</p>
<p>Instances of <tt class="docutils literal"><span class="pre">genshi.core.Attrs</span></tt> are now immutable. Filters
manipulating the attributes in a stream may need to be updated. Also,
the <tt class="docutils literal"><span class="pre">Attrs</span></tt> class no longer automatically wraps all attribute names
in <tt class="docutils literal"><span class="pre">QName</span></tt> objects, so users of the <tt class="docutils literal"><span class="pre">Attrs</span></tt> class need to do this
themselves. See the documentation of the <tt class="docutils literal"><span class="pre">Attrs</span></tt> class for more
information.</p>
</div>
<div class="section">
<h1><a id="upgrading-from-markup" name="upgrading-from-markup">3   Upgrading from Markup</a></h1>
<p>Prior to version 0.3, the name of the Genshi project was "Markup". The
name change means that you will have to adjust your import statements
and the namespace URI of XML templates, among other things:</p>
<ul class="simple">
<li>The package name was changed from "markup" to "genshi". Please
adjust any import statements referring to the old package name.</li>
<li>The namespace URI for directives in Genshi XML templates has changed
from <tt class="docutils literal"><span class="pre">http://markup.edgewall.org/</span></tt> to
<tt class="docutils literal"><span class="pre">http://genshi.edgewall.org/</span></tt>. Please update the <tt class="docutils literal"><span class="pre">xmlns:py</span></tt>
declaration in your template files accordingly.</li>
</ul>
<p>Furthermore, due to the inclusion of a text-based template language,
the class:</p>
<pre class="literal-block">
markup.template.Template
</pre>
<p>has been renamed to:</p>
<pre class="literal-block">
genshi.template.MarkupTemplate
</pre>
<p>If you've been using the Template class directly, you'll need to
update your code (a simple find/replace should do—the API itself
did not change).</p>
</div>
    <div id="footer">
      Visit the Genshi open source project at
      <a href="http://genshi.edgewall.org/">http://genshi.edgewall.org/</a>
    </div>
  </div>
</body>
</html>
